Skip to main content
Version: 0.2.1

Use Cases

Common Admin Workflows​

This page walks through ten frequent Terraform Cloud/Enterprise (TFC/E) administration tasks and shows how to accomplish each using the TFCE GraphQL API. When the built‑in GraphQL schema is sufficient, we provide example queries. For more specialized needs, we highlight the custom queries you can add (and note where API support is missing).

Multi-org selection: Unless noted otherwise, workspace-centric queries accept optional includeOrgs and excludeOrgs arguments. Omitting includeOrgs (or passing an empty array) uses every organization you can access; any organization listed in both arrays is excluded.

1. View all workspaces with open runs​

TFC does not currently surface a global filter for run status. Use the custom workspacesWithOpenRuns query to find all workspaces with at least one run matching a given status filter (e.g. planning/applying):

query WorkspacesWithOpenRuns(
  $orgs: [String!]!
  $runFilter: RunFilter!
) {
  workspacesWithOpenRuns(
    includeOrgs: $orgs
    runFilter: $runFilter
  ) {
    id
    name
    runs(filter: $runFilter) {
      id
      status
      message
      createdAt
    }
  }
}
# Variables:
{
  "orgs": ["my-org"],
  "runFilter": { "status": { "_in": ["planning", "applying"] } }
}

The GraphQL layer pages through all workspaces and tests the first page of runs for each, so this remains efficient even at scale.

2. Identify resource‑heavy states​

Use the built‑in resourceCount field on Workspace to find workspaces whose current state contains more than N resources:

query HeavyWorkspaces($orgs: [String!]!, $min: Int!) {
  workspaces(
    includeOrgs: $orgs
    filter: { resourceCount: { _gt: $min } }
  ) {
    id
    name
    resourceCount
  }
}

3. Bulk export secrets or variables​

You can page through all workspaces and then retrieve variables per workspace. For example, to dump every variable across every workspace:

query ExportAllVariables($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    id
    name
    variables {
      key
      value
      sensitive
      category
    }
  }
}

Our resolvers automatically page through large result sets (variables is fetched lazily under the hood).

4. Map workspace → policy sets​

The GraphQL schema already supports bi‑directional mapping between policy sets and workspaces. To see which workspaces each policy set applies to:

query PolicySetWorkspaces($org: String!) {
  policySets(organization: $org) {
    id
    name
    workspaces {
      id
      name
    }
  }
}

If you prefer workspace‑centric output, you can also nest a policySets field under each Workspace (this will require adding a reverse lookup on Workspace, see note below).

5. Audit users across teams​

Use nested relationships to audit every team’s membership:

query OrgTeamsUsers($org: String!) {
  organization(name: $org) {
    teams {
      id
      name
      users {
        id
        username
        email
      }
    }
  }
}

This leverages built‑in pagination and filtering on the teams and users connections.

6. Detect drift from VCS​

To compare the last run’s commit SHA with your VCS HEAD, fetch the new ingressAttributes.commitSha (and related VCS metadata) on the configurationVersion:

query WorkspaceDrift($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    id
    name
    runs(filter: { status: { _in: ["applied"] } }) {
      configurationVersion {
        ingressAttributes {
          commitSha
          commitUrl
          branch
        }
      }
    }
  }
}

7. Generate Terraform “stack graph”​

Fetch the full workspace dependency graph in a single call using the new stackGraph query:

query StackGraph($orgs: [String!]!) {
  stackGraph(includeOrgs: $orgs) {
    id
    workspaceName
    sourceableName
    createdAt
  }
}

The stackGraph query returns a list of run-trigger edges (workspace dependencies) across all workspaces in the selected organizations.

8. Export workspace inputs & outputs​

You can combine the variables (inputs) and state version outputs (outputs) per workspace:

query WorkspaceIO($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    id
    name
    variables {
      key
      value
      sensitive
    }
    # Assuming you know the last applied configuration version:
    latestConfiguration: configurationVersions(filter: { status: { _eq: "applied" } }) {
      id
      downloadUrl
    }
    stateVersionOutputs(stateVersionId: "<LATEST_CONFIG_ID>") {
      key
      value
    }
  }
}

9. Search across state versions​

Finding which state version contains a given resource requires downloading the JSON state for each version. We now expose the hosted JSON download URL on StateVersion.

query SearchStateVersions($org: String!, $workspace: String!) {
  stateVersions(orgName: $org, workspaceName: $workspace) {
    id
    serial
    hostedJsonStateDownloadUrl
  }
}

Download hostedJsonStateDownloadUrl and scan for your resource (e.g. aws_s3_bucket.foo).

For feedback or contributions on any of these use cases, please open an issue or PR!

Top 25 GraphQL Queries for Terraform Cloud & Enterprise​

Below is a list of 25 high-value GraphQL query use cases for Terraform Cloud (TFC) and Terraform Enterprise (TFE). Each section includes the persona, their goal, and an example GraphQL query (with variables). Use cases that require additional API endpoints or schema extensions are marked accordingly.

1. Identify All Active Runs for Concurrency Management​

Persona: Platform Engineer / SRE
Goal: Get a unified view of all active runs (planning, applying, etc.) across every workspace to troubleshoot pipeline bottlenecks.

Query:

query ActiveRuns(
  $orgs: [String!]!
  $runFilter: RunFilter!
) {
  workspacesWithOpenRuns(
    includeOrgs: $orgs
    runFilter: $runFilter
  ) {
    id
    name
    runs(filter: $runFilter) {
      id
      status
      createdAt
      triggerReason
    }
  }
}

Variables:

{
  "orgs": ["my-org"],
  "runFilter": { "status": { "_in": ["pending", "planning", "applying"] } }
}

2. Find Stale Workspaces with No Recent Runs​

Persona: Platform Admin
Goal: List workspaces whose last apply or run occurred before a given threshold (e.g. 90 days ago).

Query:

query StaleWorkspaces(
  $orgs: [String!]!
  $threshold: DateTime!
) {
  workspaces(
    includeOrgs: $orgs
    filter: { latestChangeAt: { _lt: $threshold } }
  ) {
    id
    name
    latestChangeAt
  }
}

Variables:

{
  "orgs": ["my-org"],
  "threshold": "2021-01-01T00:00:00Z"
}

3. Detect Workspaces with Drift​

Persona: SRE / Platform Engineer
Goal: Find all workspaces where infrastructure drift has been detected (resources changed outside Terraform).

Query (top-level):

query DriftedResults($workspaceId: ID!) {
  assessmentResults(
    workspaceId: $workspaceId
    filter: { drifted: { _eq: true } }
  ) {
    id
    drifted
    createdAt
  }
}

Note: To aggregate this across workspaces or to count drifted resources per workspace, we need a nested assessmentResults field on Workspace and/or an aggregated drift count. Please provide the corresponding API endpoint so we can extend the schema.

4. List Workspaces Failing Policy Checks​

Persona: Compliance Auditor
Goal: See which workspaces currently have failing Sentinel/OPA policy checks.

Query:

# TODO: implement nested or top-level `policyEvaluations` query to list workspaces with failures.

Note: The current schema exposes policyEvaluations(taskStageId), but does not directly link it to Run or Workspace for filtering. Please provide the API endpoint for policy evaluations per run or workspace stage.

5. Audit Overridden Policy Violations​

Persona: Security/Compliance Officer
Goal: Identify runs where a policy was violated but overridden by an admin.

Query:

# TODO: implement `runs` or `policyChecks` override detection query.

Note: Requires overrideReason and approver metadata from the policy checks API. Please provide the REST endpoint for fetching overridden policy check details.

6. Identify Workspaces Missing Mandatory Policy Sets​

Persona: Compliance Auditor
Goal: Ensure all workspaces have the required policy sets applied.

Query:

# TODO: list all workspaces and attached `policySets`, then filter missing mandatory set.

Note: Please provide the API endpoint for fetching workspace–policy set attachments (or confirm if workspace.policySets is available).

7. Module Usage and Reuse Across Organization​

Persona: Platform Engineer / Module Author
Goal: Get insight into how internal Terraform modules are used across workspaces.

Query:

# TODO: implement `registryModules` or similar query for module usage counts.

Note: Please provide the API endpoint for fetching module usage by workspace.

8. Track Provider Versions in Use (Provider Version Drift)​

Persona: Platform Engineer / Security
Goal: See all Terraform providers (and versions) in use to detect outdated or unapproved versions.

Query:

# TODO: implement `providers` view query returning provider name, version, and workspace counts.

Note: Please provide the API endpoint for listing provider versions in use across workspaces.

9. Terraform Version Consistency Audit​

Persona: Platform Engineer
Goal: Ensure all teams use approved Terraform CLI versions.

Query:

query TerraformVersions($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    name
    terraformVersion
  }
}

10. Find Largest Workspaces by Resource Count​

Persona: Platform Engineer
Goal: Identify workspaces managing the most resources for performance tuning or splitting.

Query:

query LargestWorkspaces($orgs: [String!]!, $min: Int!) {
  workspaces(
    includeOrgs: $orgs
    filter: { resourceCount: { _gt: $min } }
  ) {
    id
    name
    resourceCount
  }
}

11. Aggregate Recent Run Failures​

Persona: SRE / DevOps Engineer
Goal: List all failed runs (errored or canceled) in the last X days across the organization.

Query:

query RecentFailures($orgs: [String!]!, $since: DateTime!) {
  workspaces(includeOrgs: $orgs) {
    name
    runs(filter: { status: { _in: ["errored", "canceled"] }, createdAt: { _gt: $since } }) {
      id
      status
      message
      createdAt
    }
  }
}

12. Spot Long-Pending or Stuck Runs​

Persona: SRE
Goal: Find runs that have been waiting for manual input or stuck in queue longer than expected.

Query:

query StuckRuns($orgs: [String!]!, $statuses: [String!]!) {
  workspacesWithOpenRuns(includeOrgs: $orgs, runFilter: { status: { _in: $statuses } }) {
    id
    name
    runs(filter: { status: { _in: $statuses } }) {
      id
      status
      createdAt
    }
  }
}

Variables:

{
  "orgs": ["my-org"],
  "statuses": ["pending", "plan_queued", "policy_checking"]
}

13. Audit Auto-Apply vs. Manual Approval Settings​

Persona: DevOps / Compliance Engineer
Goal: Ensure critical environments require manual applies and lower environments use auto-apply for agility.

Query:

query AutoApplySettings($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    name
    autoApply
    environment
  }
}

14. Workspace Team Access Matrix​

Persona: Org Admin
Goal: Review which teams have access to which workspaces and at what level.

Query:

# TODO: implement `teamAccess` query for workspace-team relationships.

Note: Please provide the API endpoint for workspace–team access listings.

15. User Membership and Activity Audit​

Persona: Org Admin / Auditor
Goal: List all users in the org, their team memberships, roles, and last activity.

Query:

# TODO: extend `users` query to include nested `teams` and activity timestamps.

Note: Confirm if last login or activity metadata is available via API.

16. Identify Cost Estimation Outliers​

Persona: FinOps / Cloud Cost Manager
Goal: Find runs with cost estimates above a threshold or summarize cost estimates per workspace.

Query:

# TODO: implement `costEstimates` fields on `Run` to filter by estimated cost.

Note: Please provide the cost estimation API endpoint.

17. Map Workspace Run Triggers (Dependency Graph)​

Persona: Platform Engineer
Goal: Map run triggers between workspaces to understand cross-workspace dependencies.

Query:

query WorkspaceRunTriggers($workspaceId: ID!, $direction: String!) {
  runTriggers(workspaceId: $workspaceId, filter: { type: { _eq: $direction } }) {
    id
    workspaceName
    sourceableName
    createdAt
  }
}

18. Verify Variable Set Coverage​

Persona: Platform Engineer
Goal: Ensure global variable sets (e.g. credentials) are properly attached to all relevant workspaces.

Query:

# TODO: list `variableSets` and their workspace attachments or add nested field.

Note: Please provide the API endpoint for variable set attachments.

19. Search for a Specific Resource Across States​

Persona: Cloud Engineer
Goal: Quickly find if any workspace manages a given resource address or resource ID.

Query:

# TODO: implement state resource search / index query across state versions.

Note: Requires an API to search state JSON for resource addresses across all workspaces.

20. Ensure Sensitive Variables Are Properly Marked​

Persona: Security Engineer
Goal: Audit workspace variables to ensure secrets are not exposed in plaintext.

Query:

query PlaintextSecrets($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    name
    variables(filter: { sensitive: { _eq: false } }) {
      key
      category
      value
    }
  }
}

21. Multi-Org Terraform Usage Summary​

Persona: Enterprise Platform Owner
Goal: Aggregate workspace counts, resource counts, etc. across multiple organizations.

Query:

# TODO: extend top-level `organizations` query with nested stats (requires multi-org support).

22. Fetch Key Outputs from Multiple Workspaces​

Persona: SRE / Integrator
Goal: Retrieve specific output values (e.g. service_endpoint) from a set of workspaces.

Query:

# TODO: use `stateVersionOutputs` across multiple workspaces with filtering.

23. Find Unassigned or Ungrouped Workspaces​

Persona: Platform Admin
Goal: Identify workspaces missing project assignments or required tags.

Query:

query UngroupedWorkspaces($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs, filter: { projectName: { _eq: null } }) {
    id
    name
    tagNames
  }
}

24. Audit Workspace Execution Modes (Agent vs. Cloud)​

Persona: Platform Engineer
Goal: Review which workspaces use Terraform Cloud agents vs hosted execution.

Query:

query ExecutionModes($orgs: [String!]!) {
  workspaces(includeOrgs: $orgs) {
    id
    name
    executionMode
    agentPool
  }
}

25. Highlight Runs with Large Plan Changes​

Persona: SRE / Change Manager
Goal: Identify runs that propose a very large number of resource adds/changes/deletes.

Query:

# TODO: include plan summary fields (e.g. `resourceAddCount`, `resourceChangeCount`, `resourceDestroyCount`).

For any use case marked TODO above, please share the corresponding Terraform Cloud/Enterprise REST API endpoint so we can implement them in the GraphQL schema and resolvers.